Skip to main content

Asynchronous Notification

Once a transfer to a bank account is processed, PayBy will send the result to the merchant. The merchant must handle the notification and respond accordingly. The actual time the funds arrive depends on the settlement times of the receiving bank.

Note

  1. Duplicate Notifications: The same notification may be sent multiple times. Your system must be able to handle duplicate notifications correctly.

  2. Retry Mechanism: If PayBy does not receive a valid or timely response from your system, it will consider the notification failed and retry sending it. PayBy will retry sending the notification up to 7 times at intervals of 2, 10, 10, 60, 120, 360, and 900 minutes, but final delivery success is not guaranteed.

  3. Uncertain Order Status: If the order status is unclear or no notification is received, merchants should actively query the transfer status via the API.

  4. Signature Verification: Notification requests are signed using PayBy’s RSA private key. Merchants must verify the signature using the PayBy public key, which can be downloaded from the merchant portal. The signing method is the same as for regular API requests.

Request​

Http Header​

Attributes

  • Content-Type String Required

    The media type. Required for operations with a request body. The value is application/<format>, where format is json.

    Example value: application/json

  • sign String Required

    When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.

Http Body​

  • notify_timestamp Timestamp Required

    The timestamp when PayBy sent the request.

    Example value: 1586849271877

  • notify_id String Required

    The unique identification number of this notification within the PayBy system.

    Example value: 202004140007474501

  • transferToBankOrder Object

    Attributes

    • requestTime Timestamp Required

      • Time the request was initiated.
      • Example value: 1581493898000

    • merchantOrderNo String Required

      • Unique identifier for the merchant's order.
      • Example value: S10000

    • orderNo String Required

      • Unique identifier for the PayBy transaction.
      • Example value: O1000

    • product String Required

      • Name of the product or service.
      • Example value: Transfer To Bank

    • status String Required

      • Current status of the order.
      • Example value: -

    • paymentInfo TransferToBankPaymentInfo

      • Detailed information about the payment processing, especially related to fees and timing.

      • Example value:

        {
          "arrivalTime": 1585133416000,
          "payerFeeAmount": {
            "amount": 0,
            "currency": "AED"
          }
        }

      • payerFeeAmount Money

        • The fee charged to the sender (payer), including amount and currency.
        • Example value: -

      • arrivalTime Timestamp (milliseconds, 3-digit precision)

        • Timestamp when the funds were expected to arrive or did arrive.
        • Example value: 1585133416000

    • amount Money Required

      • Transaction amount.
      • Example value: (empty)

    • holderName String Required

      • SHA-256 hash of the original name.
      • Example value: (empty)

    • Iban String Required

      • SHA-256 hash of the original IBAN.
      • Example value: (empty)

    • swiftCode String

      • SWIFT code of the beneficiary bank.
      • Example value: (empty)

    • memo String

      • Remarks or notes for the payment.
      • Example value: (empty)

    • notifyUrl String

      • URL for backend notifications.
      • Example value: (empty)

    • failDes String

      • Reason for order failure.
      • Example value: -

    • beneficiaryAddress String

      • SHA-256 hash of the original address.
      • Example value: (empty)

    • bankReference String

      • Reference number associated with the bank.
      • Example value: (empty)

    • fundoutAmount Money

      • Amount credited to the beneficiary.
      • Example value: (empty)

    • rate BigDecimal

      • Exchange rate used for the transaction.
      • Example value: (empty)

    • networkCode String Required

      • Financial network used.
      • Example value: LOCAL

    • countryCode String

      • Country code of the beneficiary bank.
      • Example value: -

    • bankName String

      • Name of the beneficiary bank.
      • Example value: -

    • fedwireCode String

      • Fedwire account code.
      • Example value: -

    • intermediaryBank String

      • SWIFT code of the intermediary bank.
      • Example value: -

    • branchName String

      • Name of the bank branch.
      • Example value: (empty)

    • beneficiaryType String Required

      • Type of beneficiary account.
      • Example value: IBAN

    • purposeCode String

      • Code indicating the purpose of the transaction.
      • Example value: COM
  • **notify_time** String

    The parameter is deprecated. Please use the notify_timestamp instead.

  • **_input_charset** String

    The parameter is deprecated.

Notification Sample​

// Http Header
{
    "Content-Type": "application/json; charset=UTF-8"
}

// Http Body
{
    "_input_charset": "UTF-8",
    "notify_id": "202004140007474501",
    "notify_time": "20200414113800",
    "transferToBankOrder": {
        "amount": {
            "amount": 0.02,
            "currency": "AED"
        },
        "holderName": "00d74f270d2251e8fa6e7f3b1ea06bd3b5f32dfe4719f9df60982c55b24e4898",
        "iban": "1fc44f25c178c422f705054c669cfa6133f6dc8e1fe24b3d96f847667db8b92c",
        "memo": "company single pay",
        "merchantOrderNo": "M188573109026",
        "notifyUrl": "http://www.yoursite.com",
        "orderNo": "911586849271010217",
        "paymentInfo": {
            "arrivalTime": 1586849273000,
            "payerFeeAmount": {
                "amount": 5.0,
                "currency": "D"
            }
        },
        "product": "Transfer To Bank",
        "requestTime": 1586849271877,
        "status": "SUCCESS",
        "swiftCode": "BBME AEAD"
    }
}

Response​

Please reply success after receiving the notification, otherwise PayBy will send the notification repeatedly for the same order.

Http Header​

  • Content-Type String Required

    The media type. Required for operations with a request body. The value is application/<format>, where format is json.

    Example value: application/json

Http Body​

  • response String Required

    Example value: Success

// Http Header
{
 "Content-Type": "application/json; charset=UTF-8" 
}

// Http Body
{
    "response":"SUCCESS"
}

Response Codes​

CodeMessageDescriptionWorkaround
0SUCCESSRequest was successful—
400INVALID_PARAMETERInvalid request parametersAdjust request parameters
400REQUESTTIME_TOO_EARLYRequest time is too far in the pastAdjust request time
400REQUESTTIME_TOO_LATERRequest time is too far in the futureAdjust request time
402RATE_LIMIT_REJECTToo many requests in a short timeReduce request frequency
403UNAUTHORIZEDAPI access not authorizedContact PayBy
404SERVICE_NOT_AVAILABLEAPI service is currently unavailableContact PayBy
500SYSTEM_ERRORInternal system errorContact PayBy and retry later
504SERVICE_TIMEOUTRequest timed outRetry later
601RISK_FAILRisk control validation failedAdjust business logic
62002ORDER_FAILUREAttempted to cancel or refund a failed orderModify merchant order number
62004MERCHANT_ORDER_NO_NOT_EXISTOrder with the given merchant order number does not existModify merchant order number
62016MERCHANT_ORDER_NO_EXISTDuplicate order number with different business parametersModify order number
62026PRODUCT_IS_NOT_APPLIEDProduct not applied forApply for the product
62028ORDER_SUCCESSOrder has already been successfully processedModify merchant order number
62029ORDER_CREATEDOrder has already been createdModify merchant order number
62076FUND_OUT_ABILITY_SUPPORTEDnetworkCode or fundoutCurrencyCode not enabled or unsupportedContact PayBy
62101WRONG_IBAN_FORMATInvalid IBAN formatCorrect IBAN format
62102NAME_NOT_FOUNDName could not be retrieved via IBANCorrect IBAN
62103QUERY_API_UNAVAILABLEQuery API is currently unavailableRetry later
62094THE_ENTERED_COUNTRY_CODE_IS_INVALIDInvalid country codeAdjust request parameters
62095THE_ENTERED_CITY_CODE_IS_INVALIDInvalid city codeAdjust request parameters